Annotations

Apache Wink provides several annotations in addition to those defined by the JAX-RS specification. The following section describes these annotations in detail.

@Workspace Annotation

The purpose of the @Workspace annotation is to associate a "Collection Resource" with a workspace element and collection elements in an APP Service Document.

Reference For more information regarding the APP Service Document, refer to section 5.4 APP Service Document

The workspaceTitle annotation parameter specifies the title of the workspace and the collectionTitle annotation parameter specifies the title of the collection.

@Workspace Annotation Specification

@Workspace Annotation Example

The following example demonstrates the use of @Workspace annotation on two resources in order to have the auto-generated APP service document contain the information about them.

Given the following collection Resources definitions, ResourceA and ResourceB, the result is displayed in the "Auto Generated APP Service Document" table that follows.

ResourceA Definition

@Workspace(workspaceTitle = "Services", collectionTitle = "Service1")
@Path("services/service1")
public class ResourceA {
    @POST
    @Produces("text/plain")
    @Consumes({"application/atom+xml", "application/xml"})
    public String getText() {return "hey there1";}
}

ResourceB Definition

@Workspace(workspaceTitle = "Services", collectionTitle = "Service2")
@Path("services/service2")
public class ResourceB {
    @POST
    @Produces("text/plain")
    @Consumes({"application/atom+xml", "application/xml"})
    public String getText() {return "hey there2";}
}

The auto-generated APP Service Document is as follows:

Auto Generated APP Service Document

<service xmlns:atom=http://www.w3.org/2005/Atom
         xmlns="http://www.w3.org/2007/app">
    <workspace>
        <atom:title>Services</atom:title>
        <collection href="services/service1">
            <atom:title>Service1</atom:title>
            <accept>application/xml</accept>
            <accept>application/atom+xml</accept>
        </collection>
        <collection href="services/service2">
            <atom:title>Service2</atom:title>
            <accept>application/xml</accept>
            <accept>application/atom+xml</accept>
        </collection>
    </workspace>
</service>

@Asset Annotation

The @Asset annotation is a marker annotation used by the Apache Wink runtime in order to identify an entity as an Asset.

Reference For more information about Assets refer to section 5.9 Assets.

@Asset Annotation Specification

@Scope Annotation

The JAX-RS specification defines the default lifecycle behavior for resources and providers, and the option for controlling the lifecycle through the javax.ws.rs.core.Application class.

Apache Wink provides the @Scope annotation to specify the lifecycle of a provider or resource.

@Scope Annotation Specification

Resource Example

The following example illustrates how to define a resource with a singleton lifecycle.

@Scope(ScopeType.SINGLETON)
@Path("service1")
public class ResourceA {
    ...
}

Provider Example

The following example illustrates how to define a provider with a prototype lifecycle.

@Scope(ScopeType.PROTOTYPE)
@Provider
public class EntityProvider implements MessageBodyReader<String> {
    ...
}

@Parent Annotation

The @Parent annotation provides the ability to define a base template URI for the URI specified in a resources @Path annotation.
If a resource is annotated with the @Parent annotation, the Apache Wink runtime calculates the final resource template by first retrieving the value of the @Parent annotation, which holds the parent resource class, and then concatenates the resource path template definition to the path template definition of the parent resource.

@Parent Annotation Specification

Example 1

@Path("services")
public class ParentResource {
    ...
}

Example 2

@Parent(BaseResource.class)
@Path("service1")
public class ResourceA {
    ...
}

Explanation

In the example, the user defined two resources: A ParentResource and ResourceA. ParentResource defines the @Path annotation to associate it with "services" URI. ResourceA defines the @Path annotation to associate it with "service1" URI and defines ParentResource to be its parent by specifying it in the @Parent annotation. In this case, the final URI path for ResourceA is "services/service1".